﻿<?xml version="1.0" encoding="utf-8"?>
<developerWhitePaperDocument
  xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
  xmlns:xlink="http://www.w3.org/1999/xlink">

  <summary>
    <para>Optional summary abstract</para>
  </summary>

  <byline>
    <para>Byline2</para>
  </byline>

  <date>
    <para>Date</para>
  </date>

  <summarySection>
    <content>
    <para>The primary goal of the toolkit is to simplify the process of creating
    custom forms for WSS 3.0 workflows.  To this end, the toolkit provides a set 
    of base classes and host ASP.NET pages that peform the common work.  This 
    allows workflow developers to focus on their process.</para>
    </content>
  </summarySection>

  <!-- <downloadCenterLink>Optional info about downloadable content</downloadCenterLink> -->

  <!-- <appliesTo>Optional "applies to" info</appliesTo> -->

  <!-- <contents>Optional contents info</contents> -->

  <introduction>
    <para>When writing a workflow that uses supporting forms such as association forms, 
    instantiation forms, or modification forms, the developer is requried to 
    create a fairly large amount of code to handle standard tasks that must be 
    performed by all workflows.  By taking these common classes and extracting
    them from the process, the WSS3 Workflow Toolkit simplifies this process.</para>    
    <mediaLink>
 		<image placement="center" xlink:href="0068e671-d00b-4aec-9719-18700f453c9b"/>
	</mediaLink>	
	<para>Extraction of common behavior is handled in two different ways.  To 
	extract the common functional behaviors, a base classes is used.  When 
	extracting common visual aspects, an ASP.NET User Control (.ASCX) is hosted
	in a standard base class.</para>
  </introduction>

  <!-- Add one or more top-level section elements.  These are collapsible.
       If using <autoOutline /> tag, add an address attribute to identify
       it so that it can be jumped to with a hyperlink. -->
  <section address="Concepts">
    <title>Toolset Concepts</title>
    <content>
      <para>The WSS3 Workflow Toolkit contains a host page for each type of 
      workflow form.  Each host page is made up of two parts, an .ASPX file and 
      a base class.  The host page contains all the ASP.NET markup needed to
      create a web page that be visually consistent with the pages supplied by
      WSS 3.0.  Since only a small part of the page changes for each different
      workflow package, a placeholder control is located on the host page any
      place there could be custom content.</para>
      <para>-- show an image of a host control with it's placeholder controls --</para>
      <para>When the WSS3 Workflow Toolkit solution package is installed, the 
      host pages are installed to the _layout folders.  Each workflow package
      that references these host pages, provides custom meta data that is used 
      to populate the host page's placeholders</para>
      <para>-- show an sample of the metadata mapped to a placeholder control -- </para>
      <para>Each time the host page is
      loaded, the current workflow's metadata is retrieved and processed to 
      find the path of an ASP.NET User Control (.ASCX) to load into the 
      placeholder.  This process allows the workflow package developer to use
      the toolkit's host page instead of writing their own.  The package 
      developer now creates an ASP.NET User Control (.ASCX) and registers it 
      with the appropriate metadata and the toolkit's framework takes care of 
      the rest.</para>      
    </content>
  </section>
  <section address="FormTypes">
    <title>Workflow Control Types</title>
    <content>
      <para>WSS 3.0 Workflow supports 4 different types of forms.
		<list class="bullet">
		  <listItem>Association Forms</listItem>
		  <listItem>Instantiation Forms</listItem>
		  <listItem>Modification Forms</listItem>
		  <listItem>Task Forms</listItem>
		</list>	
	  </para>
	  <para>Each of these forms performs a unique role in the workflow's 
	  lifecycle, but there are some similarities.  For example the Association, 
	  Instantiation, and Modification forms all load and save their data as a 
	  string.  The most common method of using this string is to store XML in
	  this string.  To simplify this process, the framework automatically 
	  deserializes and serializes this string as a .NET class for you.</para>
	  <para>When using a custom Association, Instantiation, or Modification form, 
	  a custom data class is defined by the developer that will represent the 
	  incoming and outgoing data.  Another similarity between forms is that the
	  Association and Instantiation forms often use the same data structure for
	  their data.  The WSS3 Workflow Toolkit requires that Association and 
	  Instantiation data are the same.  This data is referred to as Configuration 
	  Data.</para>
	  <para>Based on the groupings made based on these similarities, the WSS3 
	  workflow toolkit identifies three different types of custom controls:
		<list class="bullet">
		  <listItem><link xlink:href="ee3d53a4-f75f-441a-9dc9-ea03d89c8b93">Configuration Controls</link></listItem>
		  <listItem><link xlink:href="98770a16-0d0b-46ca-808f-2f63bb206d74">Modification Controls</link></listItem>
		  <listItem><link xlink:href="eb877d5a-0aea-4b29-b42e-85d25cabb8e3">Task Controls</link></listItem>
		</list>
	  </para>
	  <para>When using the toolkit developers define the types of controls they
	  will need, create the appropriate ASP.NET User Controls (.ASCX), and then
	  register them using the workflow's metadata.  This allows the framework to
	  handle the common work, while allowing the developer to focus on the 
	  details of their custom form.</para>
    </content>
  </section>

  <conclusion>
    <content>
	  <para>The following topics will define each type of control and walk 
	  through the process of using each one in a real world example.</para>
    </content>
  </conclusion>

  <relatedTopics>
    <link xlink:href="ee3d53a4-f75f-441a-9dc9-ea03d89c8b93">Configuration Forms</link>
    <link xlink:href="eb877d5a-0aea-4b29-b42e-85d25cabb8e3">Task Forms</link>
    <link xlink:href="98770a16-0d0b-46ca-808f-2f63bb206d74">Modification Forms</link>
    <link xlink:href="cc82ff9f-f843-43b4-94dd-125c5b4dea0d">Bulk Task Forms</link>
    <!-- One or more of the following:
         - A local link
         - An external link
         - A code entity reference

    <link xlink:href="Other Topic's ID">Link text</link>
    <externalLink>
        <linkText>Link text</linkText>
        <linkAlternateText>Optional alternate link text</linkAlternateText>
        <linkUri>URI</linkUri>
    </externalLink>
    <codeEntityReference>API member ID</codeEntityReference>

    Examples:

    <link xlink:href="00e97994-e9e6-46e0-b420-5be86b2f8278">Some other topic</link>

    <externalLink>
        <linkText>SHFB on CodePlex</linkText>
        <linkAlternateText>Go to CodePlex</linkAlternateText>
        <linkUri>http://www.codeplex.com/SHFB</linkUri>
    </externalLink>

    <codeEntityReference>T:TestDoc.TestClass</codeEntityReference>
    <codeEntityReference>P:TestDoc.TestClass.SomeProperty</codeEntityReference>
    <codeEntityReference>M:TestDoc.TestClass.#ctor</codeEntityReference>
    <codeEntityReference>M:TestDoc.TestClass.#ctor(System.String,System.Int32)</codeEntityReference>
    <codeEntityReference>M:TestDoc.TestClass.ToString</codeEntityReference>
    <codeEntityReference>M:TestDoc.TestClass.FirstMethod</codeEntityReference>
    <codeEntityReference>M:TestDoc.TestClass.SecondMethod(System.Int32,System.String)</codeEntityReference>
    -->
  </relatedTopics>

  <!-- <additionalInformation>Optional additional info</additionalInformation> -->

  <!-- <authorBio>Optional author bio</authorBio> -->

</developerWhitePaperDocument>
